<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>?refresh | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'docs-refresh.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docs-refresh.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docs-refresh.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/docs-refresh.html" rel="nofollow" target="_blank">../en/docs-refresh.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="docs.html">Document APIs</a></span>
»
<span class="breadcrumb-node"><code class="literal">?refresh</code></span>
</div>
<div class="navheader">
<span class="prev">
<a href="docs-multi-termvectors.html">« Multi term vectors API</a>
</span>
<span class="next">
<a href="optimistic-concurrency-control.html">Optimistic concurrency control »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="docs-refresh"></a><code class="literal">?refresh</code><a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/refresh.asciidoc">edit</a>
</h2>
</div></div></div>
<p>The <a class="xref" href="docs-index_.html" title="Index API">Index</a>, <a class="xref" href="docs-update.html" title="Update API">Update</a>, <a class="xref" href="docs-delete.html" title="Delete API">Delete</a>, and
<a class="xref" href="docs-bulk.html" title="Bulk API">Bulk</a> APIs support setting <code class="literal">refresh</code> to control when changes made
by this request are made visible to search. These are the allowed values:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
Empty string or <code class="literal">true</code>
</span>
</dt>
<dd>
Refresh the relevant primary and replica shards (not the whole index)
immediately after the operation occurs, so that the updated document appears
in search results immediately. This should <span class="strong strong"><strong>ONLY</strong></span> be done after careful thought
and verification that it does not lead to poor performance, both from an
indexing and a search standpoint.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for</code>
</span>
</dt>
<dd>
Wait for the changes made by the request to be made visible by a refresh before
replying. This doesn’t force an immediate refresh, rather, it waits for a
refresh to happen. Elasticsearch automatically refreshes shards that have changed
every <code class="literal">index.refresh_interval</code> which defaults to one second. That setting is
<a class="xref" href="index-modules.html#dynamic-index-settings" title="Dynamic index settings">dynamic</a>. Calling the <a class="xref" href="indices-refresh.html" title="Refresh API">Refresh</a> API or
setting <code class="literal">refresh</code> to <code class="literal">true</code> on any of the APIs that support it will also
cause a refresh, in turn causing already running requests with <code class="literal">refresh=wait_for</code>
to return.
</dd>
<dt>
<span class="term">
<code class="literal">false</code> (the default)
</span>
</dt>
<dd>
Take no refresh related actions. The changes made by this request will be made
visible at some point after the request returns.
</dd>
</dl>
</div>
<h4>
<a id="_choosing_which_setting_to_use"></a>Choosing which setting to use<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/refresh.asciidoc">edit</a>
</h4>
<p>Unless you have a good reason to wait for the change to become visible, always
use <code class="literal">refresh=false</code> (the default setting). The simplest and fastest choice is to omit the <code class="literal">refresh</code> parameter from the URL.</p>
<p>If you absolutely must have the changes made by a request visible synchronously
with the request, you must choose between putting more load on
Elasticsearch (<code class="literal">true</code>) and waiting longer for the response (<code class="literal">wait_for</code>).
Here are a few points that should inform that decision:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The more changes being made to the index the more work <code class="literal">wait_for</code> saves
compared to <code class="literal">true</code>. In the case that the index is only changed once every
<code class="literal">index.refresh_interval</code> then it saves no work.
</li>
<li class="listitem">
<code class="literal">true</code> creates less efficient indexes constructs (tiny segments) that must
later be merged into more efficient index constructs (larger segments). Meaning
that the cost of <code class="literal">true</code> is paid at index time to create the tiny segment, at
search time to search the tiny segment, and at merge time to make the larger
segments.
</li>
<li class="listitem">
Never start multiple <code class="literal">refresh=wait_for</code> requests in a row. Instead batch them
into a single bulk request with <code class="literal">refresh=wait_for</code> and Elasticsearch will start
them all in parallel and return only when they have all finished.
</li>
<li class="listitem">
If the refresh interval is set to <code class="literal">-1</code>, disabling the automatic refreshes,
then requests with <code class="literal">refresh=wait_for</code> will wait indefinitely until some action
causes a refresh. Conversely, setting <code class="literal">index.refresh_interval</code> to something
shorter than the default like <code class="literal">200ms</code> will make <code class="literal">refresh=wait_for</code> come back
faster, but it’ll still generate inefficient segments.
</li>
<li class="listitem">
<code class="literal">refresh=wait_for</code> only affects the request that it is on, but, by forcing a
refresh immediately, <code class="literal">refresh=true</code> will affect other ongoing request. In
general, if you have a running system you don’t wish to disturb then
<code class="literal">refresh=wait_for</code> is a smaller modification.
</li>
</ul>
</div>
<h4>
<a id="refresh_wait_for-force-refresh"></a><code class="literal">refresh=wait_for</code> Can Force a Refresh<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/refresh.asciidoc">edit</a>
</h4>
<p>If a <code class="literal">refresh=wait_for</code> request comes in when there are already
<code class="literal">index.max_refresh_listeners</code> (defaults to 1000) requests waiting for a refresh
on that shard then that request will behave just as though it had <code class="literal">refresh</code> set
to <code class="literal">true</code> instead: it will force a refresh. This keeps the promise that when a
<code class="literal">refresh=wait_for</code> request returns that its changes are visible for search
while preventing unchecked resource usage for blocked requests. If a request
forced a refresh because it ran out of listener slots then its response will
contain <code class="literal">"forced_refresh": true</code>.</p>
<p>Bulk requests only take up one slot on each shard that they touch no matter how
many times they modify the shard.</p>
<h4>
<a id="_examples_13"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/refresh.asciidoc">edit</a>
</h4>
<p>These will create a document and immediately refresh the index so it is visible:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /test/_doc/1?refresh
{"test": "test"}
PUT /test/_doc/2?refresh=true
{"test": "test"}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1572.console"></div>
<p>These will create a document without doing anything to make it visible for
search:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /test/_doc/3
{"test": "test"}
PUT /test/_doc/4?refresh=false
{"test": "test"}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1573.console"></div>
<p>This will create a document and wait for it to become visible for search:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /test/_doc/4?refresh=wait_for
{"test": "test"}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1574.console"></div>
</div>
<div class="navfooter">
<span class="prev">
<a href="docs-multi-termvectors.html">« Multi term vectors API</a>
</span>
<span class="next">
<a href="optimistic-concurrency-control.html">Optimistic concurrency control »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>